Resource URL: /platform/<<version=1>>/protocols/smb/shares/<SHARE>

    Overview: This resource applies the standard collection item pattern to
              individual SMB shares.  SHARE in the resource path is the share
              name.

     Methods: GET, PUT, DELETE

********************************************************************************

Method GET: Retrieve share.

       URL: GET /platform/<<version=1>>/protocols/smb/shares/<SHARE>

Query arguments:
           scope=<enum> Where <enum> is one of user, default, effective.  If
                        specified as "effective" or not specified, all fields
                        are returned.  If specified as "user", only fields with
                        non-default values are shown.  If specified as
                        "default", the original values are returned.
resolve_names=<boolean> If true, resolve group and user names in personas.
          zone=<string> Zone which contains this share.

GET response body schema:
{
  "type": [
    {
      "additionalProperties": false, 
      "type": "object", 
      "description": "A list of errors that may be returned.", 
      "properties": {
        "errors": {
          "items": {
            "additionalProperties": false, 
            "type": "object", 
            "description": "An object describing a single error.", 
            "properties": {
              "field": {
                "type": "string", 
                "description": "The field with the error if applicable."
              }, 
              "message": {
                "type": "string", 
                "description": "The error message."
              }, 
              "code": {
                "type": "string", 
                "description": "The error code."
              }
            }
          }, 
          "type": "array"
        }
      }
    }, 
    {
      "additionalProperties": false, 
      "type": "object", 
      "properties": {
        "shares": {
          "minItems": 0, 
          "items": {
            "required": true, 
            "type": "object", 
            "properties": {
              "file_create_mode": {
                "type": "integer", 
                "description": "File create mode bits."
              }, 
              "ntfs_acl_support": {
                "type": "boolean", 
                "description": "Support NTFS ACLs on files and directories."
              }, 
              "directory_create_mask": {
                "type": "integer", 
                "description": "Directory create mask bits."
              }, 
              "access_based_enumeration_root_only": {
                "type": "boolean", 
                "description": "Access-based enumeration on only the root directory of the share."
              }, 
              "file_create_mask": {
                "type": "integer", 
                "description": "File create mask bits."
              }, 
              "path": {
                "required": true, 
                "type": [
                  "null", 
                  "string"
                ], 
                "description": "Path of share within /ifs."
              }, 
              "inheritable_path_acl": {
                "type": "boolean", 
                "description": "Set the inheritable ACL on the share path."
              }, 
              "allow_variable_expansion": {
                "type": "boolean", 
                "description": "Allow automatic expansion of variables for home directories."
              }, 
              "id": {
                "required": true, 
                "type": [
                  "null", 
                  "string"
                ], 
                "description": "Share ID."
              }, 
              "hide_dot_files": {
                "type": "boolean", 
                "description": "Hide files and directories that begin with a period '.'."
              }, 
              "create_permissions": {
                "enum": [
                  "default acl", 
                  "inherit mode bits", 
                  "use create mask and mode"
                ], 
                "type": "string", 
                "description": "Create permissions for new files and directories in share."
              }, 
              "strict_locking": {
                "type": "boolean", 
                "description": "Specifies whether byte range locks contend against SMB I/O."
              }, 
              "mangle_map": {
                "items": {
                  "type": "string"
                }, 
                "type": "array", 
                "description": "Character mangle map."
              }, 
              "zid": {
                "required": true, 
                "type": "integer", 
                "description": "Numeric ID of the access zone which contains this SMB share"
              }, 
              "run_as_root": {
                "items": {
                  "type": "object", 
                  "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                  "properties": {
                    "type": {
                      "enum": [
                        "user", 
                        "group", 
                        "wellknown"
                      ], 
                      "type": "string", 
                      "description": "Specifies the type of persona, which must be combined with a name."
                    }, 
                    "id": {
                      "minLength": 0, 
                      "type": "string", 
                      "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'.", 
                      "maxLength": 261
                    }, 
                    "name": {
                      "minLength": 0, 
                      "type": "string", 
                      "description": "Specifies the persona name, which must be combined with a type.", 
                      "maxLength": 255
                    }
                  }
                }, 
                "type": "array", 
                "description": "Allow account to run as root."
              }, 
              "browsable": {
                "type": "boolean", 
                "description": "Share is visible in net view and the browse list."
              }, 
              "description": {
                "type": "string", 
                "description": "Description for this SMB share."
              }, 
              "impersonate_guest": {
                "enum": [
                  "always", 
                  "bad user", 
                  "never"
                ], 
                "type": "string", 
                "description": "Specify the condition in which user access is done as the guest account."
              }, 
              "auto_create_directory": {
                "type": "boolean", 
                "description": "Automatically create home directories."
              }, 
              "directory_create_mode": {
                "type": "integer", 
                "description": "Directory create mode bits."
              }, 
              "allow_delete_readonly": {
                "type": "boolean", 
                "description": "Allow deletion of read-only files in the share."
              }, 
              "access_based_enumeration": {
                "type": "boolean", 
                "description": "Only enumerate files and folders the requesting user has access to."
              }, 
              "allow_execute_always": {
                "type": "boolean", 
                "description": "Allows users to execute files they have read rights for."
              }, 
              "csc_policy": {
                "enum": [
                  "manual", 
                  "documents", 
                  "programs", 
                  "none"
                ], 
                "type": "string", 
                "description": "Client-side caching policy for the shares."
              }, 
              "permissions": {
                "description": "Specifies an ordered list of permission modifications.", 
                "minItems": 0, 
                "items": {
                  "type": "object", 
                  "description": "Specifies properties for an Access Control Entry.", 
                  "properties": {
                    "permission_type": {
                      "enum": [
                        "allow", 
                        "deny"
                      ], 
                      "type": "string", 
                      "description": "Determines whether the permission is allowed or denied.", 
                      "required": true
                    }, 
                    "trustee": {
                      "required": true, 
                      "type": "object", 
                      "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                      "properties": {
                        "type": {
                          "enum": [
                            "user", 
                            "group", 
                            "wellknown"
                          ], 
                          "type": "string", 
                          "description": "Specifies the type of persona, which must be combined with a name."
                        }, 
                        "id": {
                          "minLength": 0, 
                          "type": "string", 
                          "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'.", 
                          "maxLength": 261
                        }, 
                        "name": {
                          "minLength": 0, 
                          "type": "string", 
                          "description": "Specifies the persona name, which must be combined with a type.", 
                          "maxLength": 255
                        }
                      }
                    }, 
                    "permission": {
                      "enum": [
                        "full", 
                        "change", 
                        "read"
                      ], 
                      "type": "string", 
                      "description": "Specifies the file system rights that are allowed or denied.", 
                      "required": true
                    }
                  }
                }, 
                "maxItems": 4294967295, 
                "uniqueItems": true, 
                "type": "array"
              }, 
              "name": {
                "required": true, 
                "type": [
                  "null", 
                  "string"
                ], 
                "description": "Share name."
              }, 
              "host_acl": {
                "items": {
                  "type": "string", 
                  "description": "<'allow:'|'deny:'><'ALL'|IP-range|subnet|fqdn>[' EXCEPT '<IP-range|subnet|fqdn>]."
                }, 
                "type": "array", 
                "description": "An ACL expressing which hosts are allowed access. A deny clause must be the final entry."
              }, 
              "change_notify": {
                "enum": [
                  "all", 
                  "norecurse", 
                  "none"
                ], 
                "type": "string", 
                "description": "Level of change notification alerts on the share."
              }, 
              "impersonate_user": {
                "type": "string", 
                "description": "User account to be used as guest account."
              }, 
              "mangle_byte_start": {
                "type": "integer", 
                "description": "Specifies the wchar_t starting point for automatic byte mangling."
              }, 
              "oplocks": {
                "type": "boolean", 
                "description": "Support oplocks."
              }, 
              "strict_flush": {
                "type": "boolean", 
                "description": "Handle SMB flush operations."
              }
            }
          }, 
          "type": "array", 
          "maxItems": 4294967295
        }
      }
    }
  ]
}

********************************************************************************

Method PUT: Modify share. All input fields are optional, but one or more must
            be supplied.

       URL: PUT /platform/<<version=1>>/protocols/smb/shares/<SHARE>

Query arguments:
zone=<string> Zone which contains this share.

PUT request body schema:
{
  "required": true, 
  "type": "object", 
  "properties": {
    "file_create_mode": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "integer", 
          "description": "File create mode bits."
        }
      ]
    }, 
    "ntfs_acl_support": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Support NTFS ACLs on files and directories."
        }
      ]
    }, 
    "directory_create_mask": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "integer", 
          "description": "Directory create mask bits."
        }
      ]
    }, 
    "access_based_enumeration_root_only": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Access-based enumeration on only the root directory of the share."
        }
      ]
    }, 
    "file_create_mask": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "integer", 
          "description": "File create mask bits."
        }
      ]
    }, 
    "path": {
      "type": "string", 
      "description": "Path of share within /ifs."
    }, 
    "inheritable_path_acl": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Set the inheritable ACL on the share path."
        }
      ]
    }, 
    "allow_variable_expansion": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Allow automatic expansion of variables for home directories."
        }
      ]
    }, 
    "hide_dot_files": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Hide files and directories that begin with a period '.'."
        }
      ]
    }, 
    "create_permissions": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "enum": [
            "default acl", 
            "inherit mode bits", 
            "use create mask and mode"
          ], 
          "type": "string", 
          "description": "Create permissions for new files and directories in share."
        }
      ]
    }, 
    "strict_locking": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Specifies whether byte range locks contend against SMB I/O."
        }
      ]
    }, 
    "zone": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "string", 
          "description": "Name of the access zone to which to move this SMB share"
        }
      ]
    }, 
    "mangle_map": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "items": {
            "type": "string"
          }, 
          "type": "array", 
          "description": "Character mangle map."
        }
      ]
    }, 
    "run_as_root": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "items": {
            "type": "object", 
            "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
            "properties": {
              "type": {
                "enum": [
                  "user", 
                  "group", 
                  "wellknown"
                ], 
                "type": "string", 
                "description": "Specifies the type of persona, which must be combined with a name."
              }, 
              "id": {
                "minLength": 0, 
                "type": "string", 
                "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'.", 
                "maxLength": 261
              }, 
              "name": {
                "minLength": 0, 
                "type": "string", 
                "description": "Specifies the persona name, which must be combined with a type.", 
                "maxLength": 255
              }
            }
          }, 
          "type": "array", 
          "description": "Allow account to run as root."
        }
      ]
    }, 
    "browsable": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Share is visible in net view and the browse list."
        }
      ]
    }, 
    "description": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "string", 
          "description": "Description for this SMB share."
        }
      ]
    }, 
    "impersonate_guest": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "enum": [
            "always", 
            "bad user", 
            "never"
          ], 
          "type": "string", 
          "description": "Specify the condition in which user access is done as the guest account."
        }
      ]
    }, 
    "auto_create_directory": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Automatically create home directories."
        }
      ]
    }, 
    "directory_create_mode": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "integer", 
          "description": "Directory create mode bits."
        }
      ]
    }, 
    "allow_delete_readonly": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Allow deletion of read-only files in the share."
        }
      ]
    }, 
    "access_based_enumeration": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Only enumerate files and folders the requesting user has access to."
        }
      ]
    }, 
    "allow_execute_always": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Allows users to execute files they have read rights for."
        }
      ]
    }, 
    "csc_policy": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "enum": [
            "manual", 
            "documents", 
            "programs", 
            "none"
          ], 
          "type": "string", 
          "description": "Client-side caching policy for the shares."
        }
      ]
    }, 
    "permissions": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "description": "Specifies an ordered list of permission modifications.", 
          "minItems": 0, 
          "items": {
            "type": "object", 
            "description": "Specifies properties for an Access Control Entry.", 
            "properties": {
              "permission_type": {
                "enum": [
                  "allow", 
                  "deny"
                ], 
                "type": "string", 
                "description": "Determines whether the permission is allowed or denied.", 
                "required": true
              }, 
              "trustee": {
                "required": true, 
                "type": "object", 
                "description": "Specifies properties for a persona, which consists of either a 'type' and a 'name' or an 'ID'.", 
                "properties": {
                  "type": {
                    "enum": [
                      "user", 
                      "group", 
                      "wellknown"
                    ], 
                    "type": "string", 
                    "description": "Specifies the type of persona, which must be combined with a name."
                  }, 
                  "id": {
                    "minLength": 0, 
                    "type": "string", 
                    "description": "Specifies the serialized form of a persona, which can be 'UID:0', 'USER:name', 'GID:0', 'GROUP:wheel', or 'SID:S-1-1'.", 
                    "maxLength": 261
                  }, 
                  "name": {
                    "minLength": 0, 
                    "type": "string", 
                    "description": "Specifies the persona name, which must be combined with a type.", 
                    "maxLength": 255
                  }
                }
              }, 
              "permission": {
                "enum": [
                  "full", 
                  "change", 
                  "read"
                ], 
                "type": "string", 
                "description": "Specifies the file system rights that are allowed or denied.", 
                "required": true
              }
            }
          }, 
          "maxItems": 4294967295, 
          "uniqueItems": true, 
          "type": "array"
        }
      ]
    }, 
    "name": {
      "type": "string", 
      "description": "Share name."
    }, 
    "host_acl": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "items": {
            "type": "string", 
            "description": "<'allow:'|'deny:'><'ALL'|IP-range|subnet|fqdn>[' EXCEPT '<IP-range|subnet|fqdn>]."
          }, 
          "type": "array", 
          "description": "An ACL expressing which hosts are allowed access. A deny clause must be the final entry."
        }
      ]
    }, 
    "change_notify": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "enum": [
            "all", 
            "norecurse", 
            "none"
          ], 
          "type": "string", 
          "description": "Level of change notification alerts on the share."
        }
      ]
    }, 
    "impersonate_user": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "string", 
          "description": "User account to be used as guest account."
        }
      ]
    }, 
    "mangle_byte_start": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "integer", 
          "description": "Specifies the wchar_t starting point for automatic byte mangling."
        }
      ]
    }, 
    "oplocks": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Support oplocks."
        }
      ]
    }, 
    "strict_flush": {
      "type": [
        {
          "enum": [
            "@DEFAULT"
          ], 
          "type": "string"
        }, 
        {
          "type": "boolean", 
          "description": "Handle SMB flush operations."
        }
      ]
    }
  }
}

There is no JSON response body for this method.

********************************************************************************

Method DELETE: Delete the share.

          URL: DELETE /platform/<<version=1>>/protocols/smb/shares/<SHARE>

Query arguments:
zone=<string> Zone which contains this share.

There is no JSON response body for this method.
